home *** CD-ROM | disk | FTP | other *** search
/ Info-Mac 3 / Info_Mac_1994-01.iso / Graphics / Utility / PoVUtils1.1 / Mac POV Utils 1.1 / POV-Utils Docs 1.1 < prev   
Text File  |  1993-03-23  |  14KB  |  306 lines
  1. POV-Utilities for the Macintosh
  2. ===============================
  3. 3/23/93, version 1.1
  4. Collected and ported to the Macintosh
  5. by Eduard [esp] Schwan
  6.  
  7. Introduction
  8. ------------
  9. The POV-Utilities are a rather diverse collection of programs that have
  10. been designed to extend or ease the use of ray tracers.  This diversity
  11. extends to the authors of the utilities as well, since many people have
  12. created them.  Many of these utilities have been around for a while, but
  13. mostly on the IBM PC platform only.
  14.  
  15. The intent of the author of a utility is usually to take care of an
  16. immediate need, not to create a general purpose piece of source code.
  17. Therefore, the utilities have been written in everything from IBM PC batch
  18. files and Unix AWK scripts, to BASIC and C. Currently, only the C
  19. utilities have been converted to the Macintosh, since they are the
  20. easiest to port.  There are more C utilities that have not yet been
  21. tackled, but that's just a challenge, I guess.  
  22.  
  23. To give you an idea of the variety of these utilities, here's a
  24. one-sentence synopsis of each utility currently in the Macintosh suite: 
  25.  
  26. ** Coil Generator - Bill Kirby
  27. Generates intertwined coiled toruses of spheres.
  28.  
  29.  * Connect the Dots (CDTS) - Truman Brown
  30. Takes an input text file of XYZ coordinates and writes a POV-Ray
  31. output file that consists of spheres and connecting cylinders
  32. between them. 
  33.  
  34.  * Dat2POV - Drew Wells
  35. Does a 95% automatic source conversion from POV-Ray 0.5 source to
  36. POV-Ray 1.0 source syntax.  
  37.  
  38.  * DXF2POV - Aaron A. Collins
  39. Converts AutoCAD DXF (interchange) text files into POV-Ray
  40. source files.
  41.  
  42.  * "Lissa" Lissajous Generator - Eduard [esp] Schwan
  43. Generates a CTDS file of a lissajous-style 3-D woven mesh
  44. curve of dots.
  45.  
  46.  * POV Suds Generator - Sam Hobbs & Dan Farmer
  47. Generates a POV-Ray source file of "osculating spheres" of different
  48. sizes and textures.
  49.  
  50.  * Raw2POV - Steve Anger
  51. Converts a text file of raw triangle vertex coordinates into a POV-Ray
  52. source file of either regular or smooth triangles.
  53.  
  54.  * Shell Generator - Dan Farmer
  55. Generates a POV-Ray (or CTDS) source file of a snail-shell spiral
  56. of spheres.
  57.  
  58.  * Sponge Generator - Stephen Coy
  59. Generates a POV-Ray source file of a recursive cube lattice
  60. of spheres.
  61.  
  62.  * Swoop - Douglas Otwell
  63. Converts a "SWOOP" language input text file into a raw triangle text file.
  64. This raw file can then be run through Raw2POV to create a POV-Ray source
  65. file.  The SWOOP file can describe iterative translations and rotations of
  66. 2-D polygons, creating a 3-D extruded surface. This object is made up of
  67. triangles on the POV-Ray side.
  68.  
  69. Requirements
  70. ------------
  71. -Any Macintosh (Mac Plus to Quadra)
  72. -System 6.0.4 or better (tested mostly under System 7)
  73. -Color Monitor preferred but not required
  74. -Some utilities may require 2 MB or more of memory, but most utilities
  75.  will run in 1 MB.
  76.  
  77. Features
  78. --------
  79. -Easily pop between utilities using menus
  80. -Uses (slightly) more intuitive dialog boxes for user parameters
  81. -Supports multiple monitors (dialogs follow the status window)
  82. -Status window text can be saved to a text file for logging purposes.
  83.  
  84. General Instructions
  85. --------------------
  86. POV-Utilities is a typical Macintosh application (whatever that means.)
  87. Just double-click it, check out the nifty startup graphics, and choose the
  88. utility of your choice from the "Utilities" menu.  Oh, you can peek at the
  89. About box too!
  90.  
  91. Each utility behaves similarly, so here's a general step-by-step guide:
  92.  
  93. Choose the utility you want from the Utilities menu.
  94.  
  95. You are now presented with a dialog box of options to fill out.  Enter
  96. the appropriate values, select the input or output file, and click the
  97. "OK" button.  Note that some utilities REQUIRE that you pick an output
  98. file.  The OK button will be dimmed until you do so.
  99.  
  100. The utility will run, displaying progress information as it goes.
  101. Depending on the utility, it could take anywhere from seconds to
  102. minutes to complete.  While it is running, the cursor changes to a
  103. wristwatch, reminding you that the computer is busy pondering a way to
  104. escape its current situation.  Some of the utilities display dots or
  105. other progress information as they run.  When the utility does complete,
  106. the cursor returns to an arrow.
  107.  
  108. If, for some reason, you wish to cancel the running utility before it
  109. completes, you may hold down the command key and press the period key,
  110. or choose "Stop" from the File menu.
  111.  
  112. WARNING: Unfortunately, cancelling the running utility will most likely
  113. leave the utility in an unstable state, possibly with files left open. You
  114. can run other utilities without a problem, but you will probably not be
  115. able to run the stopped utility again without getting spurious file
  116. errors.  It won't hurt anything, but you will find that you need to quit
  117. the POV-Utilities application, and restart it.  After this, all will be
  118. well again.  This is just an unfortunate side-effect of allowing the user
  119. to exit the utility to exit at any time.
  120.  
  121. A time stamp is displayed in the status window, each time a utility
  122. starts or stops.  This lets you know how long a utility takes to
  123. do its thing.
  124.  
  125. When the utility is finished, you may pick "Save As" from the File
  126. menu to save the Status window content as a text file.  This may
  127. be useful for keeping track of which files you have processed, or
  128. for timing different utilities, etc.
  129.  
  130. Specific Instructions
  131. ---------------------
  132. The best information for each utility is currently provided by
  133. each author of that utility.  Therefore, partially out of
  134. consideration of the great talents of these authors, and partly
  135. as a dodge so I don't have to try to consolidate and rewrite this
  136. vast variety of documentation, I have included the original
  137. documents for each utility, as-is.  This means that you will need
  138. to read over those documents to better understand the specifics
  139. of each utility.  You won't get it all in this one.  Also, I have
  140. put the name and e-mail address (where known) for each author
  141. in each utility's dialog box.
  142.  
  143. The Tutorials
  144. -------------
  145. I am also posting a TUTORIAL folder along with this package, which has
  146. some documentation and example files, made specifcally to show you how to
  147. use each of these utilities with POV-Ray.  These examples were created by
  148. me, not by the utilities authors, and thus I bear full blame for any
  149. mistakes or inaccuracies in these examples, not them. 
  150.  
  151. Currently, the turorial package is not quite complete.  I have tutorials
  152. for all the scene creation utilities, but not all the conversion
  153. utilities. I welcome feedback on the package, and hope to finish it sooner
  154. or later. I have posted it as a Macintosh archive, and also as an IBM PC
  155. archive. 
  156.  
  157. The Tutorial documentation and example files are FreeWare, and the author
  158. reserves all rights to them.  They may not be distributed separately from
  159. the Tutorial package. 
  160.  
  161. Known Bugs
  162. ----------
  163. POVSUDS - Telling it to create a ton of suds, and a too-small area to
  164. create them in may result in the utility unsuccessfully hunting forever
  165. for places to put suds.  You will need to cancel and try again with fewer
  166. suds, a larger area, or smaller radii. 
  167.  
  168. Cancelling a utility (cmd-period) often leaves that particular utility in
  169. an unstable state.  It cannot be run again unless you quit the
  170. POV-Utilities application and run it again.  Other utilities will be OK. 
  171.  
  172. Although this is a "final" release, the ported utilities have only been
  173. minimally tested on the Macintosh (by my standards, anyway.)  I am very
  174. interested in hearing of any problems you have with this.  Please try to
  175. give as much information about what hardware and software you are running
  176. this on, what INITs/extensions you have, and what led up to the problem.
  177. The more information I get, the more quickly I can find and (hopefully)
  178. fix the problem. Currently, the utilities all seem to be working well,  I
  179. know of no nasty crashes, even on Quadras.  
  180.  
  181. The Future
  182. ----------
  183. In this release of the Macintosh POV-Utilities, all the utilities are
  184. grouped into one large monolithic Macintosh application.  This was
  185. primarily done out of expedience for the Macintosh author, not because it
  186. was necessarily the best thing for the user.  The next release will likely
  187. see these as separate applications, each with a nice System 7 drag-n-drop
  188. interface and life of its own.  This would also better handle the
  189. non-synchronized release schedule of all the independent utilities.
  190.  
  191. With AppleEvent and maybe even AppleScript support, these utilities could
  192. become quite powerful.  I also wish to port some other important utilities
  193. that I haven't gotten to yet.  There's POVGen, FrGen, SPD, etc... We need
  194. some image conversion utilities (Targa/GIF/PICT), and maybe the C
  195. Beutifier that is used to help format the source code and scene files.  We
  196. also need a POV 1.0 to 2.0 source converter.  I am also interested in
  197. further automating the creation of animation files for POV-Ray (watch for
  198. POV-Ray 2.0!)  Of course, if you find (or create) utilities that you would
  199. like me to know about, please contact me!
  200.  
  201. Source Code
  202. -----------
  203. The latest source code for most of these utilities can be found on
  204. either CompuServe or America Online, or by contacting the authors.
  205. I do not have permission to redistribute their source code, and do not
  206. want to stay on top of the constant updates.  Therefore, I have sent
  207. my changes back to each author in the hopes that they will roll them
  208. into their future releases.  That way, the re-integration of their
  209. source back to the Mac will be much easier.
  210.  
  211. Some Source Code Notes
  212. ----------------------
  213. The POV-Utilities are a collection of stand-alone programs
  214. that each perform useful functions.  In the Macintosh
  215. world, we have combined these into a single mongo
  216. application. The idea behind the source code setup in this
  217. project is to insure a MINIMUM set of changes to the
  218. standard C programs, so that any updates to these source
  219. files from the original authors will MINIMALLY impact our
  220. Macintosh changes, and that the Macintosh changes to these
  221. files minimally impacts the authors' works, and is still
  222. portable across platforms.
  223.  
  224. How do you do that?
  225. For example, there is a utility program called CTDS.  It
  226. has a main program source file called CTDS.C.  I created
  227. some code to prompt for the parameters for this utility,
  228. and called the files CTDS.mac.c and CTDS.mac.h. CTDS.mac.h
  229. also includes a #define that changes the main() function in
  230. CTDS.C into a regular function call called CTDS_main(). We
  231. can now link together many "main programs" and call them as
  232. subroutines from our true Mac main program, contained in
  233. the file POV-Utilities.c. The only change to CTDS.C is the
  234. addition of the following lines of code, near the top of
  235. the file:
  236.     #if defined(applec) || defined(THINK_C)
  237.     // if using Macintosh, include user interface stuff
  238.     #include "CTDS.mac.h"
  239.     #endif
  240. Another important point is to make all your C functions
  241. "static."  This insures that when independent utilities are
  242. linked together, their identically named functions don't
  243. collide at link time. The final proposal is to try to
  244. allocate any large global data structures dynamically
  245. (malloc) as opposed to declaring them as static global
  246. variables.  This cuts down on global data space
  247. requirements.
  248.  
  249. Please follow these guidelines when adding new utilities,
  250. creating a standard stand-alone application with all the
  251. usual parameter passing of K&R C, and a separate file that
  252. contains the Mac-specific user-interface routines to
  253. prompt the user for those same parameters.  This will allow
  254. any new Mac utilities to flow easily back the other way,
  255. to our other POV-Ray computer-kin.
  256.  
  257. Bottom Line
  258. -----------
  259. This software is a collection of FreeWare and Public Domain software,
  260. ported to the Macintosh.  This Macintosh application is provided as
  261. FreeWare.  The author reserves all rights to the Macintosh application.
  262. It may be freely distributed, but not for profit.  Feel free to send
  263. (Mac-related) bug reports, enhancement ideas, new utilities, etc. to
  264. Eduard Schwan.
  265.  
  266. Additional References & Information
  267. -----------------------------------
  268. The POV-Ray raytracer is an ongoing FreeWare project being developed on
  269. CompuServe.  The executable and the source code can be found there, on the
  270. Graphics Development forum (GO GRAPHDEV.)  You can also find it on America
  271. Online, on the PC Graphics (PGR:Company Support:POV Ray) forum.
  272.  
  273. Image Lab, Tim Wegner, Waite Group Press, 1992.  This book talks about
  274. POV-Ray, and a couple of the utilities.
  275.  
  276. Credits
  277. -------
  278. The original authors really deserve 99% of the kudos for their ingenuity. 
  279.  
  280. Jim Nitchals began porting and enhancing many of the POV-Utilities prior
  281. to my mucking about with them.  He has also beta tested them, and insured
  282. the source compiled under Think C. 
  283.  
  284. I have incorporated many of Jim's enhancements into the utilities, and
  285. have been sending the proposed updates back to the appropriate authors. I
  286. also created the TUTORIAL materials, posted elsewhere nearby. 
  287.  
  288. Of course, none of this could have happened if I had paid the proper
  289. amount of attention to my wife and children.  Their infinite patience and
  290. affection have pulled me through some otherwise meaningless late nights of
  291. coding, testing and documenting. Therefore, all I ask is that if you find
  292. these works useful, please let me (and my family!) know that my work has
  293. benefitted you as well.  And of course, let the authors know that you are
  294. enjoying their tools too! 
  295.  
  296. Thank you,
  297. Happy Raytracing!
  298. [esp]
  299.  
  300. Author Contact
  301. --------------
  302. Eduard [esp] Schwan
  303. CompuServe: 71513,2161
  304. AppleLink: jl.mactech
  305. Internet: 71513.2161@compuserve.com
  306.